home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat2 / standard / msgop.z / msgop
Encoding:
Text File  |  2002-10-03  |  13.3 KB  |  265 lines
  1.  
  2.  
  3.  
  4. mmmmssssggggoooopppp((((2222))))                                                              mmmmssssggggoooopppp((((2222))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _mmmm_ssss_gggg_oooo_pppp: _mmmm_ssss_gggg_ssss_nnnn_dddd, _mmmm_ssss_gggg_rrrr_cccc_vvvv - message operations
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_tttt_yyyy_pppp_eeee_ssss_...._hhhh_>>>>
  13.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_iiii_pppp_cccc_...._hhhh_>>>>
  14.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_mmmm_ssss_gggg_...._hhhh_>>>>
  15.  
  16.      _iiii_nnnn_tttt _mmmm_ssss_gggg_ssss_nnnn_dddd_((((_iiii_nnnn_tttt _mmmm_ssss_qqqq_iiii_dddd_,,,, _cccc_oooo_nnnn_ssss_tttt _vvvv_oooo_iiii_dddd _****_mmmm_ssss_gggg_pppp_,,,,
  17.           _ssss_iiii_zzzz_eeee______tttt _mmmm_ssss_gggg_ssss_zzzz_,,,, _iiii_nnnn_tttt _mmmm_ssss_gggg_ffff_llll_gggg_))))_;;;;
  18.  
  19.      _iiii_nnnn_tttt _mmmm_ssss_gggg_rrrr_cccc_vvvv_((((_iiii_nnnn_tttt _mmmm_ssss_qqqq_iiii_dddd_,,,, _vvvv_oooo_iiii_dddd _****_mmmm_ssss_gggg_pppp_,,,,
  20.           _ssss_iiii_zzzz_eeee______tttt _mmmm_ssss_gggg_ssss_zzzz_,,,, _llll_oooo_nnnn_gggg _mmmm_ssss_gggg_tttt_yyyy_pppp_,,,, _iiii_nnnn_tttt _mmmm_ssss_gggg_ffff_llll_gggg_))))_;;;;
  21.  
  22. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  23.      _mmmm_ssss_gggg_ssss_nnnn_dddd sends a message to the queue associated with the message queue
  24.      identifier specified by _m_s_q_i_d.  _m_s_g_p points to a user defined buffer that
  25.      must contain first a field of type long integer that will specify the
  26.      type of the message, and then a data portion that will hold the text of
  27.      the message.  The following is an example of members that might be in a
  28.      user defined buffer.
  29.  
  30.               _llll_oooo_nnnn_gggg _mmmm_tttt_yyyy_pppp_eeee_;;;;    _////_**** _mmmm_eeee_ssss_ssss_aaaa_gggg_eeee _tttt_yyyy_pppp_eeee _****_////
  31.               _cccc_hhhh_aaaa_rrrr _mmmm_tttt_eeee_xxxx_tttt_[[[[_]]]]_;;;;  _////_**** _mmmm_eeee_ssss_ssss_aaaa_gggg_eeee _tttt_eeee_xxxx_tttt _****_////
  32.  
  33.      _mmmm_tttt_yyyy_pppp_eeee is a positive integer that can be used by the receiving process for
  34.      message selection.  _mmmm_tttt_eeee_xxxx_tttt is any text of length _m_s_g_s_z bytes.  _m_s_g_s_z can
  35.      range from _0000 to a system imposed maximum.
  36.  
  37.      _m_s_g_f_l_g specifies the action to be taken if one or more of the following
  38.      are true:
  39.  
  40.           The number of bytes already on the queue is equal to _mmmm_ssss_gggg______qqqq_bbbb_yyyy_tttt_eeee_ssss [see
  41.           _iiii_nnnn_tttt_rrrr_oooo(2)].
  42.  
  43.           The total number of messages on all queues system-wide is equal to
  44.           the system-imposed limit.
  45.  
  46.      These actions are as follows:
  47.  
  48.           If (_m_s_g_f_l_g_&&&&_IIII_PPPP_CCCC______NNNN_OOOO_WWWW_AAAA_IIII_TTTT) is true, the message is not sent and the
  49.           calling process returns immediately.
  50.  
  51.           If (_m_s_g_f_l_g_&&&&_IIII_PPPP_CCCC______NNNN_OOOO_WWWW_AAAA_IIII_TTTT) is false, the calling process suspends
  52.           execution until one of the following occurs:
  53.  
  54.                   The condition responsible for the suspension no longer
  55.                   exists, in which case the message is sent.
  56.  
  57.                   _m_s_q_i_d is removed from the system [see _mmmm_ssss_gggg_cccc_tttt_llll(2)].  When this
  58.                   occurs, _eeee_rrrr_rrrr_nnnn_oooo is set to _EEEE_IIII_DDDD_RRRR_MMMM, and a value of -1 is
  59.                   returned.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. mmmmssssggggoooopppp((((2222))))                                                              mmmmssssggggoooopppp((((2222))))
  71.  
  72.  
  73.  
  74.                   The calling process receives a signal that is to be caught.
  75.                   In this case the message is not sent and the calling process
  76.                   resumes execution in the manner prescribed in _ssss_iiii_gggg_nnnn_aaaa_llll(2).
  77.  
  78.      _mmmm_ssss_gggg_ssss_nnnn_dddd fails and sends no message if one or more of the following are
  79.      true:
  80.  
  81.      _EEEE_IIII_NNNN_VVVV_AAAA_LLLL         _m_s_q_i_d is not a valid message queue identifier.
  82.  
  83.      _EEEE_AAAA_CCCC_CCCC_EEEE_SSSS         Write permission is denied to the calling process [see
  84.                     _iiii_nnnn_tttt_rrrr_oooo(2)].
  85.  
  86.      _EEEE_IIII_NNNN_VVVV_AAAA_LLLL         _m_t_y_p_e is less than 1.
  87.  
  88.      _EEEE_AAAA_GGGG_AAAA_IIII_NNNN         The message cannot be sent for one of the reasons cited
  89.                     above and (_m_s_g_f_l_g_&&&&_IIII_PPPP_CCCC______NNNN_OOOO_WWWW_AAAA_IIII_TTTT) is true.
  90.  
  91.      _EEEE_IIII_NNNN_VVVV_AAAA_LLLL         _m_s_g_s_z is less than zero or greater than the system-imposed
  92.                     limit.
  93.  
  94.      _EEEE_FFFF_AAAA_UUUU_LLLL_TTTT         _m_s_g_p points to an illegal address.
  95.  
  96.      Upon successful completion, the following actions are taken with respect
  97.      to the data structure associated with _m_s_q_i_d [see intro (2)].
  98.  
  99.           _mmmm_ssss_gggg______qqqq_nnnn_uuuu_mmmm is incremented by 1.
  100.  
  101.           _mmmm_ssss_gggg______llll_ssss_pppp_iiii_dddd is set to the process ID of the calling process.
  102.  
  103.           _mmmm_ssss_gggg______ssss_tttt_iiii_mmmm_eeee is set to the current time.
  104.  
  105.      _mmmm_ssss_gggg_rrrr_cccc_vvvv reads a message from the queue associated with the message queue
  106.      identifier specified by _m_s_q_i_d and places it in the user defined structure
  107.      pointed to by _m_s_g_p.  The structure must contain a message type field
  108.      followed by the area for the message text (see the structure _mmmm_yyyy_mmmm_ssss_gggg
  109.      above).  _mmmm_tttt_yyyy_pppp_eeee is the received message's type as specified by the sending
  110.      process.  _mmmm_tttt_eeee_xxxx_tttt is the text of the message.  _m_s_g_s_z specifies the size in
  111.      bytes of mtext.  The received message is truncated to _m_s_g_s_z bytes if it
  112.      is larger than _m_s_g_s_z and (_m_s_g_f_l_g_&&&&_MMMM_SSSS_GGGG______NNNN_OOOO_EEEE_RRRR_RRRR_OOOO_RRRR) is true.  The truncated
  113.      part of the message is lost and no indication of the truncation is given
  114.      to the calling process.
  115.  
  116.      _m_s_g_t_y_p specifies the type of message requested as follows:
  117.  
  118.           If _m_s_g_t_y_p is 0, the first message on the queue is received.
  119.  
  120.           If _m_s_g_t_y_p is greater than 0, the first message of type _m_s_g_t_y_p is
  121.           received.
  122.  
  123.           If _m_s_g_t_y_p is less than 0, the first message of the lowest type that
  124.           is less than or equal to the absolute value of _m_s_g_t_y_p is received.
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. mmmmssssggggoooopppp((((2222))))                                                              mmmmssssggggoooopppp((((2222))))
  137.  
  138.  
  139.  
  140.      _m_s_g_f_l_g specifies the action to be taken if a message of the desired type
  141.      is not on the queue.  These are as follows:
  142.  
  143.           If (_m_s_g_f_l_g_&&&&_IIII_PPPP_CCCC______NNNN_OOOO_WWWW_AAAA_IIII_TTTT) is true, the calling process returns
  144.           immediately with a return value of -1 and sets _eeee_rrrr_rrrr_nnnn_oooo to _EEEE_NNNN_OOOO_MMMM_SSSS_GGGG.
  145.  
  146.           If (_m_s_g_f_l_g_&&&&_IIII_PPPP_CCCC______NNNN_OOOO_WWWW_AAAA_IIII_TTTT) is false, the calling process suspends
  147.           execution until one of the following occurs:
  148.  
  149.                   A message of the desired type is placed on the queue.
  150.  
  151.                   _m_s_q_i_d is removed from the system.  When this occurs, _eeee_rrrr_rrrr_nnnn_oooo
  152.                   is set to _EEEE_IIII_DDDD_RRRR_MMMM, and a value of -1 is returned.
  153.  
  154.                   The calling process receives a signal that is to be caught.
  155.                   In this case a message is not received and the calling
  156.                   process resumes execution in the manner prescribed in
  157.                   _ssss_iiii_gggg_nnnn_aaaa_llll(2).
  158.  
  159.      _mmmm_ssss_gggg_rrrr_cccc_vvvv fails and receives no message if one or more of the following are
  160.      true:
  161.  
  162.      _EEEE_IIII_NNNN_VVVV_AAAA_LLLL         _m_s_q_i_d is not a valid message queue identifier.
  163.  
  164.      _EEEE_AAAA_CCCC_CCCC_EEEE_SSSS         Read permission is denied to the calling process.
  165.  
  166.      _EEEE_IIII_NNNN_VVVV_AAAA_LLLL         _m_s_g_s_z is less than 0.
  167.  
  168.      _EEEE_2222_BBBB_IIII_GGGG          The length of _m_t_e_x_t is greater than _m_s_g_s_z and
  169.                     (_m_s_g_f_l_g_&&&&_MMMM_SSSS_GGGG______NNNN_OOOO_EEEE_RRRR_RRRR_OOOO_RRRR) is false.
  170.  
  171.      _EEEE_NNNN_OOOO_MMMM_SSSS_GGGG         The queue does not contain a message of the desired type
  172.                     and (_m_s_g_t_y_p_&&&&_IIII_PPPP_CCCC______NNNN_OOOO_WWWW_AAAA_IIII_TTTT) is true.
  173.  
  174.      _EEEE_FFFF_AAAA_UUUU_LLLL_TTTT         _m_s_g_p points to an illegal address.
  175.  
  176.      Upon successful completion, the following actions are taken with respect
  177.      to the data structure associated with _m_s_q_i_d [see intro (2)].
  178.  
  179.           _mmmm_ssss_gggg______qqqq_nnnn_uuuu_mmmm is decremented by 1.
  180.  
  181.           _mmmm_ssss_gggg______llll_rrrr_pppp_iiii_dddd is set to the process ID of the calling process.
  182.  
  183.           _mmmm_ssss_gggg______rrrr_tttt_iiii_mmmm_eeee is set to the current time.
  184.  
  185. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  186.      _iiii_nnnn_tttt_rrrr_oooo(2), _mmmm_ssss_gggg_cccc_tttt_llll(2), _mmmm_ssss_gggg_gggg_eeee_tttt(2), _ssss_iiii_gggg_nnnn_aaaa_llll(2).
  187.  
  188. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  189.      If _mmmm_ssss_gggg_ssss_nnnn_dddd or _mmmm_ssss_gggg_rrrr_cccc_vvvv return due to the receipt of a signal, a value of -1
  190.      is returned to the calling process and _eeee_rrrr_rrrr_nnnn_oooo is set to _EEEE_IIII_NNNN_TTTT_RRRR.  If they
  191.      return due to removal of _m_s_q_i_d from the system, a value of -1 is returned
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. mmmmssssggggoooopppp((((2222))))                                                              mmmmssssggggoooopppp((((2222))))
  203.  
  204.  
  205.  
  206.      and _eeee_rrrr_rrrr_nnnn_oooo is set to _EEEE_IIII_DDDD_RRRR_MMMM.
  207.  
  208.      Upon successful completion, the return value is as follows:
  209.  
  210.           _mmmm_ssss_gggg_ssss_nnnn_dddd returns a value of 0.
  211.  
  212.           _mmmm_ssss_gggg_rrrr_cccc_vvvv returns the number of bytes actually placed into _m_t_e_x_t.
  213.  
  214.      Otherwise, a value of -1 is returned and _eeee_rrrr_rrrr_nnnn_oooo is set to indicate the
  215.      error.
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.